Skip to content

Load API reference sidebar trees once per package or module - #2213

Merged
David Pine (IEvangelist) merged 6 commits into
mainfrom
dapine-microsoft-slim-api-reference-sidebar
Nov 20, 2026
Merged

David Pine (IEvangelist) merged 6 commits into
mainfrom
dapine-microsoft-slim-api-reference-sidebar

Conversation

@IEvangelist

@IEvangelist David Pine (IEvangelist) commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Summary

Part of a series of PRs to reduce the size of the frontend container image. This PR moves the full API reference sidebar tree out of each page's HTML for C#, TypeScript and Go: every page server-renders only a small "spine", and the full tree loads once per package or module as JSON.

Before this change, every C# package, type and member-kind page rendered its package's entire sidebar tree. On aspire.hosting.kubernetes/ingressbackendv1/properties/, that sidebar was about 255 KB, compared with about 81 KB of main content. The TypeScript and Go sidebars were already spines on main, but they only offered a link back to the module overview, not the module's catalog.

Changes:

  • Per-page spine
    • C# (src/utils/api-sidebar.ts): "Search APIs", the package Overview, and the current namespace and type with its member-kind links.
    • TypeScript and Go (ts-api-sidebar.ts, go-api-sidebar.ts): unchanged. "Search", the module Overview, and the current item and member, each with its section anchors.
  • Full tree in one file per package or module: /reference/api/{csharp,typescript,go}/{name}/sidebar.json, from a sidebar.json.ts endpoint next to each language's [package]/[module] route.
    • C# trees mirror the old sidebar: namespaces, then types, then member-kind pages.
    • TypeScript trees group items as Types, Functions and Enums; Go trees as Handles, DTOs, Enums and Functions. Both match the module overview.
    • The endpoints use the same apiDocumentCacheKey as the pages, so incremental builds still reuse them. As endpoints, they stay out of the sitemap.
  • Shared client loader (src/components/starlight/api-sidebar-tree.ts, wired up from Sidebar.astro): when the browser is idle, it fetches the JSON and builds the tree from the page's own sidebar markup, so styles and icons stay identical to Starlight's output.
    • The spine's current-page group, including its section anchors, is placed into the tree where that entry belongs. Overview pages keep their section anchors.
    • It marks the current page with aria-current, opens its parent groups, and keeps Starlight's open-group state stable, so open groups and scroll position carry over between pages in the same package or module.
    • The sidebar filter and the expand-all/collapse-all button work again once the tree loads.
    • If the fetch fails, the spine stays in place. Without JavaScript, package and module overview pages still list every item.
  • C# landing page: its sidebar now links to each package instead of including every package's tree, matching the TypeScript and Go landing pages.

Estimated savings:

Per page HTML New JSON
C# About −250 KB (Kubernetes 255 KB → 2.6 KB; Aspire.Hosting 445 KB → 2.6 KB); about −0.8 GB across roughly 5,000 pages; /reference/api/csharp/ about −2.7 MB About 0.3 MB
TypeScript +104 B (the data-api-sidebar-tree attribute); the spine is unchanged 143 modules, 0.68 MB (largest: aspire.hosting.azure.provisioning.network, 123 KB)
Go +75 B 118 modules, 0.11 MB

For TypeScript and Go, the change adds full-catalog navigation without increasing page weight; it doesn't reduce their size. Most of TypeScript's 739 MB is page content plus page chrome repeated on every page, which other PRs in this series address.

Third-party links and affiliations

None

Validation

  • npx vitest run --config vitest.config.ts tests/unit/api-sidebar.vitest.test.ts tests/unit/api-route-props.vitest.test.ts tests/unit/ts-api-sidebar.vitest.test.ts tests/unit/go-api-sidebar.vitest.test.ts tests/unit/api-reference-components.vitest.test.ts tests/unit/api-cache-key.vitest.test.ts tests/unit/api-reference-routes.vitest.test.ts: passed (7 files, 45 tests).
  • npx eslint on all changed .ts sources and tests: passed.
  • npx playwright test tests/e2e/csharp-api-sidebar.spec.ts tests/e2e/ts-api-sidebar.spec.ts tests/e2e/go-api-sidebar.spec.ts tests/e2e/api-cross-language-navigation.spec.ts --project=desktop-chromium --project=mobile-chromium, run against astro dev: passed (22 tests).
  • Manual browser check against astro dev on C#, TypeScript and Go overview, item and member pages: the full tree loaded (1,436 links for the largest TypeScript module), the current page was highlighted and its section anchors were kept, there were no duplicate links, open-group indices stayed stable across pages, and no page errors appeared.
  • The full bun run build was not run locally; CI builds the site.

Each C# package/type/member-kind page now server-renders only the search
link, package overview and the current type's member-kind links. The full
package tree is emitted once per package as /reference/api/csharp/{pkg}/sidebar.json
and swapped in on the client by cloning the spine's own SidebarSublist
markup, reusing Starlight's sl-sidebar-state persistence. The C# landing
sidebar now links to packages instead of embedding every tree.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@aspire-repo-bot

Copy link
Copy Markdown
Contributor

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #2213. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

VS Code: Open PR #2213 artifacts

This comment updates automatically when a new frontend build artifact is uploaded.

TypeScript and Go module pages keep their server-rendered spine (search,
module overview, current item/member and its section anchors). The full
module catalog, grouped like the module overview, is now emitted once per
module as /reference/api/{typescript,go}/{module}/sidebar.json and swapped
in by the shared api-sidebar-tree loader used for C#.

The loader splices the spine's current-page group (with its section
anchors) into the tree in place of the matching entry, keeps overview
section anchors, and assigns stable sl-sidebar-restore indices so open
groups persist across pages in a package or module.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist David Pine (IEvangelist) changed the title Slim the C# API reference sidebar to a per-page spine Load API reference sidebar trees once per package or module Nov 19, 2026
@IEvangelist

Copy link
Copy Markdown
Member Author

Combined validation: real aspire publish image

I merged #2215, #2214, #2213 and #2216 into the ADO deploy branch locally, then ran the same steps as pipelines/build.yml: bicep restore followed by aspire publish -o .generated (the Ev2 publish step). The resulting image was loaded with docker load and run as a container in Production mode with Redis.

Before After all four PRs
Ev2ServiceArtifactsRoot/Images/aspiredev.tar.gz ~4 GB 1.76 GB
Built HTML pages 38,344 29,134
Site output (dist) 9.8 GB 3.73 GB
wwwroot in image n/a 3.73 GB originals + 0.68 GB .br

The container starts in 11 s, /healthz returns 200, and idle memory is about 2 GB, likely from the 134 MB staticwebassets.endpoints.json.

Testing against the container

  • Layout check: 35 representative layouts (docs, splash, hub, 404, /de/ fallback, /ja/ translated, C#/TS/Go API landing, package, type and member pages) on desktop and mobile. Every page returned the expected status, with no failed requests and no page errors.
  • Full Playwright suite, CI=1 bunx playwright test, all 3 projects, reusing the container on :4322: 1,632 passed, 5 failed, 2 flaky, 107 skipped. Failures are triaged below.
  • Manual testing of the running container found no issues.
    This PR: C# pages drop about 250 KB each (for example the kubernetes member page went from 437 KB to 117 KB). TS and Go now share the same lazy tree loader (data-api-sidebar-tree-state=loaded checked on every API layout; provisioning.network loads 1,448 links). No failures attributed to this PR.

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Pages now reference /reference/api/{lang}/{name}/sidebar.json?v=<hash>,
where <hash> is the same apiDocumentCacheKey the payload carries, so the
edge can cache tree fetches indefinitely. The loader still resolves
relative hrefs against the sidebar.json folder (URL.pathname drops ?v=).

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
@IEvangelist
David Pine (IEvangelist) marked this pull request as ready for review November 20, 2026 18:11
Copilot AI balanced review requested due to automatic review settings November 20, 2026 18:11
@IEvangelist
David Pine (IEvangelist) merged commit 8b174b2 into main Nov 20, 2026
21 checks passed
@IEvangelist
David Pine (IEvangelist) deleted the dapine-microsoft-slim-api-reference-sidebar branch November 20, 2026 18:13

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The sidebar assigns a category its first TypeScript or Go item's URL, causing navigation to replace the group with that item's spine and drop sibling links; the path resolution needs correction and regression coverage.

1 open issue
What changed in this PR

This PR reduces repeated API sidebar HTML on aspire.dev by rendering small per-page navigation spines and loading shared JSON trees. It reduces C# page size while adding full-catalog navigation to TypeScript and Go pages.

Changes:

  • Adds one content-versioned sidebar JSON endpoint per package or module.
  • Introduces a shared client loader that preserves current-page links, section anchors, and sidebar state.
  • Expands unit and browser coverage for sidebar generation and navigation.
File Description
src/​frontend/​tests/​unit/​ts-api-sidebar.vitest.test.ts Tests TypeScript catalog grouping.
src/​frontend/​tests/​unit/​go-api-sidebar.vitest.test.ts Tests Go catalog grouping.
src/​frontend/​tests/​unit/​api-sidebar.vitest.test.ts Tests C# spines and compact trees.
src/​frontend/​tests/​unit/​api-sidebar-tree-src.vitest.test.ts Tests versioned tree URLs.
src/​frontend/​tests/​e2e/​ts-api-sidebar.spec.ts Checks TypeScript tree loading and navigation.
src/​frontend/​tests/​e2e/​go-api-sidebar.spec.ts Checks Go tree loading and navigation.
src/​frontend/​tests/​e2e/​csharp-api-sidebar.spec.ts Covers C# spines, trees, filtering, and no-JavaScript access.
src/​frontend/​tests/​e2e/​api-cross-language-navigation.spec.ts Checks destination trees after cross-language navigation.
src/​frontend/​src/​utils/​ts-api-sidebar.ts Builds compact TypeScript catalog trees.
src/​frontend/​src/​utils/​go-api-sidebar.ts Builds compact Go catalog trees.
src/​frontend/​src/​utils/​api-sidebar.ts Generates C# spines, package links, and compact trees.
src/​frontend/​src/​utils/​api-sidebar-tree-src.ts Resolves content-versioned tree URLs.
src/​frontend/​src/​pages/​reference/​api/​typescript/​[module]/​sidebar.json.ts Emits each TypeScript module’s tree.
src/​frontend/​src/​pages/​reference/​api/​go/​[module]/​sidebar.json.ts Emits each Go module’s tree.
src/​frontend/​src/​pages/​reference/​api/​csharp/​[package]/​sidebar.json.ts Emits each C# package’s tree.
src/​frontend/​src/​pages/​reference/​api/​csharp/​[package]/​[type]/​index.astro Supplies the current type to the spine builder.
src/​frontend/​src/​pages/​reference/​api/​csharp/​[package]/​[type]/​[memberKind].astro Supplies the current type on member-kind pages.
src/​frontend/​src/​components/​starlight/​Sidebar.astro Connects tree loading to sidebar controls.
src/​frontend/​src/​components/​starlight/​api-sidebar-tree.ts Fetches and renders shared trees while retaining page navigation.

Review effort: Balanced

function nodePath(value: string | CompactSidebarNode[], baseHref: string): string | undefined {
if (typeof value === 'string') return normalizePath(resolveHref(value, baseHref));
const first = value[0];
return first && typeof first[1] === 'string' ? normalizePath(resolveHref(first[1], baseHref)) : undefined;
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants